Image

Subcrowns

Object for images, height maps, distance maps and similar data sampled on a regularly spaced grid. The samples are referred to as pixels whose values can be represented using different types such as unsigned integers (e.g., uint8, uint16), signed integers (e.g., int8, int16), floats (e.g., float32, float64) or RGB24 (3 times uint8 for the red, green and blue channels). The locations of the regular grid points can be described in physical world units, typically in millimeters, using the so-called image world coordinate system. The image world coordinate system is left-handed and aligned with the image axes, with the x-axis pointing from left to right, and a y-axis pointing from top towards bottom, and the origin at the upper left pixel. As the coordinate system is left-handed, positive rotations are specified clock-wise. The image coordinate system is specified as a world origin coordinate of the upper left pixel (pixel center) and a pixel size (e.g., in millimeters) in the x- and y-dimensions. The image world origin and pixel size are provided as meta data in the Image object. For regular gray scale/reflectance images captured by a 2D camera, the default world origin and pixel size are (0,0) and (1,1) respectively, so that the pixel index and image world coordinate system are the same.

For height map and depth maps for which pixel values represent ranges in the physical world, there is also a scale factor available from raw pixel value to a physical world unit (typically millimeter). For compact notation, this scaling factor is referred to as pixel size in the z-dimension, and there is also a corresponding world origin in the z-dimension. The Image object meta data also has a ‘missing data’ flag that indicates if the value 0 is a reserved number representing the absence of measurement rather than the actual numeric value 0. Algorithms will then try to ignore missing data pixels in calculations instead of using the actual value 0. The missing data flag is only supported for unsigned integer types (uint8, uint16, etc) and not for signed types (int16, float32, etc.)

Image.abs(image)
Argument:
Return type:

Image

Computes the absolute value of each pixel.

Image world coordinate system handling: The operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image.

Missing data handling: There is no special handling of missing data as the value 0 remains 0 after the operation.

Image.absInplace(image)
Argument:
Return type:

Image

Inplace version of the Image.abs function that modifies the input image. See base function for full documentation.

Image.add(image1, image2)
Arguments:
Return type:

Image

Adds two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Image.addConstant(image, constant)
Arguments:

  • image (Image)

  • constant (float)

Return type:

Image

Adds a constant value to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the constant is interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.addConstantInplace(image, constant)
Arguments:

  • image (Image)

  • constant (float)

Return type:

Image

Inplace version of Image.addConstant function which modifies the input image. See base function for full documentation.

Image.addInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.add function which modifies the first input image to contain the sum of the input images. See base function for full documentation.

Image.addNoise(image, a, b, randSeed)
Arguments:

  • image (Image)

  • a (float)

  • b (float)

  • randSeed (int)

Return type:

Image

Adds a uniform noise value in the range [a,b] to all pixels in the image. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a heightmap, distance or range image, the noise interval parameters [a,b] are interpreted in image world coordinate units, e.g., millimeters, and is rescaled to a raw pixel value using the z-pixelsize and z-origin of the image. The image metadata from the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.addNoiseInplace(image, a, b, randSeed)
Arguments:

  • image (Image)

  • a (float)

  • b (float)

  • randSeed (int)

Return type:

Image

Inplace version of the Image.addNoise function that modifies the input image. See base function for full documentation.

Image.addPlane(image, plane, region)
Arguments:
Return type:

Image

Adds the value of a plane function (Shape3D) to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time.

Image world coordinate system handling: The plane is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.addPlaneInplace(image, plane, region)
Arguments:
Return type:

Image

Inplace version of the Image.addPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Image.addPolynomial(image, polynomial, region)
Arguments:
Return type:

Image

Adds the value of a 2nd order polynomial to every pixel in an image. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The polynomial is interpreted in world space and added to the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.addPolynomialInplace(image, polynomial, region)
Arguments:
Return type:

Image

Inplace version of the Image.addPolynomial function which modifies the input image by adding the value of a given polynomial. See base function for full documentation.

Image.adjustOriginZ(image, newOriginZ)
Arguments:

  • image (Image)

  • newOriginZ (float)

Return type:

Image

Adjusts the image z-origin to the given value in world coordinates, changing the raw pixel values such that the represented world coordinate values stays the same. Adjusting the z-origin to -10.0 will allow unsigned types to represent world-coordinate values from -10.0 and larger. Pixel values outside the range of the image type will be clamped. To set a new origin without changing the raw pixel values, offsetting the world coordinate values, see Image.setOriginZ.

Image world coordinate system handling: The operation keeps pixel values in the world coordinate system constant, unless underflow or overflow occurs.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.adjustOriginZInplace(image, newOriginZ)
Arguments:

  • image (Image)

  • newOriginZ (float)

Return type:

Image

Inplace version of the Image.adjustOriginZ function that modifies the input image. See base function for full documentation.

Image.aggregate(image, type, direction, region)
Arguments:
Return type:

Profile

Reduce an image to a profile along one spatial dimension, either rows or columns. If ROW is specified the aggregation will be in this direction. For a full image this produces a profile of the same length as the height of the input image. Missing data is handled and the delivered profile is in world coordinate units.

Image.applyColormap(image, colormap, minZ, maxZ, samples, invert)
Arguments:

  • image (Image)

  • colormap (View.ColorMap)

  • minZ (float)

  • maxZ (float)

  • samples (int)

  • invert (boolean)

Return type:

Image

Render an image into an RGB target image in the same way as the View.addImage function would.

Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension is scaled according to the input parameters. Input RGB images are not supported.

Missing data handling: Missing data values in the input will always be represented as a gray value independent of color map and datatype.

Image.bilateral(image, kernelSizeSpatialPix, kernelSizeRange, region)
Arguments:
Return type:

Image

Applies a bilateral filter to an image. The bilateral filter is similar to a Gauss filter but it also adaptively modifies the filter kernel to avoid smoothing over image boundaries.

Image world coordinate system handling: The kernel size in the range/z-dimension is interpreted in world scale, e.g., millimeters, it is internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates.

Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Image.binarize(image, lowerThreshold, upperThreshold, outputValue, region)
Arguments:
Return type:

Image

Applies a threshold interval (lowerThreshold, upperThreshold) to the image to create a binary image. It is possible to binarize only a specified region. This function produces an image output, to directly produce a PixelRegion output use the threshold() function instead.

Image world coordinate system handling: The input threshold values are interpreted in image world coordinates, i.e., they are converted to raw pixel thresholds within the function using the z-origin and z-pixelsize. As the output image is binary the output z-origin is set to 0 and the z-pixelsize to 1. The output image inherits the image world coordinates in the xy-dimensions.

Missing data handling: Missing data pixels are set to background, i.e., to 0 in the output image. The output image has its missing data flag turned off regardless of the flag of the input image.

Image.binarizeAdaptive(image, deltaThresholdWorld, kernelSizePix, findBright, outputValue, region)
Arguments:

  • image (Image)

  • deltaThresholdWorld (float)

  • kernelSizePix (int)

  • findBright (boolean)

  • outputValue (int)

  • region (Image.PixelRegion)

Return type:

Image

Applies an adaptive filter to the image to create a binary image. A pixel is set in the binary output image if the value is significantly larger than the average value in a surrounding region of specified size. The threshold is set as a delta value how much larger the pixel value must be in world coordinates, i.e, the delta threshold value is scaled internally with the pixel size in the z-dimension. In its base form, bright objects on dark background are found. There is a parameter to instead find dark objects on a bright background.

Image.binarizeCompare(image, referenceImage, marginWorld, findBright, outputValue, regionOfInterest)
Arguments:

  • image (Image)

  • referenceImage (Image)

  • marginWorld (float)

  • findBright (boolean)

  • outputValue (float)

  • regionOfInterest (Image.PixelRegion)

Return type:

Image

Binarizes an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the binary output image. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives an Image object as output, to get a PixelRegion output use thresholdCompare instead.

Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image. The output image inherits x,y-origin and x,y-pixelsizes but the z-origin is set to 0 and z-pixelsize to 1.

Missing data handling: Missing data pixels are excluded from the output.

Image.binarizePlane(image, lowerThreshold, upperThreshold, plane, outputValue, region)
Arguments:
Return type:

Image

Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given plane to create a binary image from a height map. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPlane function instead.

Image world coordinate system handling: The plane is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively.

Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.

Image.binarizePolynomial(image, lowerThreshold, upperThreshold, polynomial, outputValue, region)
Arguments:

  • image (Image)

  • lowerThreshold (float)

  • upperThreshold (float)

  • polynomial (float)

  • outputValue (int)

  • region (Image.PixelRegion)

Return type:

Image

Applies a threshold interval (lowerThreshold, upperThreshold) relative to the given 2nd order polynomial to create a binary image. The threshold values accounts for world coordinates (pixel size and origin in the z-dimension) if applicable. It is possible to binarize only a specified region. The thresholds may both be negative or positive, allowing selecting values strictly below or above the reference. This function produces an image output, to directly produce a PixelRegion output use the thresholdPolynomial function instead.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The polynomial is interpreted in world space which is compared with the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the output image mask has the same pixel size and origin in x,y as the input image. Along the value axis z, the pixel size and origin are reset to unit and zero respectively.

Missing data handling: No pixels marked as missing are included in the output mask. The missing data flag of the output mask image is cleared.

Image.bitShift(image, shifts)
Arguments:

  • image (Image)

  • shifts (int)

Return type:

Image

Bit shifts all pixel values in an image of unsigned integer type. This is a fast way of multiplying or dividing (integer division) image values with powers of two. Negative shift length is used for division. Note that there are no overflow or underflow checks for this operation! The operation is performed correctly both for raw pixel values and world pixel values.

There is a slight difference when shifting using positive values compared to a real multiplication when going out of bounds. The bitshift operation simply drops the most significant bit. For an image of uint8 and a pixel value of 255 this would mean that shifting once with a positive value would shift in one zero and thus producing a lower value than before (254). Ex. 1111 1111 << 0 (uint8 255) 1111 1110 << 0 (uint8 254) 1111 1100 (uint8 252)

As can be seen the behavior is not the ideal once the limit of the data type is reached. To avoid this problem use a sufficiently large image data type, or to get the a saturating behavior, see Image.multiplyConstant.

Image world coordinate system handling: If the image has a non-zero z-origin, the z-origin of the returned image is adjusted in order to keep the operation valid both for raw- and world pixels. All other origin values and all pixel sizes are respected and copied to the returned image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, additional pixels may be marked as missing.

Image.bitShiftInplace(image, shifts)
Arguments:

  • image (Image)

  • shifts (int)

Return type:

Image

Inplace version of Image.bitShift function which modifies the input image. See base function for full documentation.

Image.blur(image, kernelSizePix, region, fillMissingData)
Arguments:
Return type:

Image

Blurs an image using a constant normalized box filter kernel.

Image world coordinate system handling: The box filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image.

Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Image.canny(image, thresholdHigh, thresholdLow, region)
Arguments:
Return type:

Image

Applies Canny edge detection to find edges in an image. The Canny edge detection works with a dual threshold procedure: first strong edges are found using a high threshold value. A second lower threshold also detects weaker edges in the image, and the weaker edges that are connected with the stronger edges are kept in the output edge image. A non-maximum suppression operation is also applied to obtain 1-pixel wide edge responses. The Canny function currently only operates on uint8 images.

Image world coordinate system handling: The input thresholds are interpreted in world scale, e.g., millimeters, they are internally divided by the z-pixelsize to get raw pixel value thresholds. The output image inherits the image world coordinates in the x,y-dimensions, but the z-pixelsize is set to 1 and the z-origin to 0.

Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Image.clamp(image, minValueWorld, maxValueWorld, region, fillMissingData)
Arguments:

  • image (Image)

  • minValueWorld (float)

  • maxValueWorld (float)

  • region (Image.PixelRegion)

  • fillMissingData (boolean)

Return type:

Image

Clamps the pixel values to an interval [maxValue, minValue]. An optional region may be provided, limiting the processing to only that region. Pixels outside the region are left in an undefined state.

Image world coordinate system handling: The [maxValue, minValue] parameters are interpreted as expressed in image world coordinate units, i.e., the clamp limits are scaled internally from world (millimeter) units to raw pixel values using the origin and pixelsize in the z-dimension. The image metadata from the input image is copied to the output image.

Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image. Setting the optional fillMissingData flag, missing data pixels will be set to the minimum clamp value. If this flag is set, the output image will have its missing data flag cleared.

Image.clampInplace(image, minValueWorld, maxValueWorld, region, fillMissingData)
Arguments:

  • image (Image)

  • minValueWorld (float)

  • maxValueWorld (float)

  • region (Image.PixelRegion)

  • fillMissingData (boolean)

Return type:

Image

Inplace version of the Image.clamp function that modifies the input image. See base function for full documentation.

Image.clampPlane(image, plane, region, fillMissingData)
Arguments:
Return type:

Image

Clamps image pixel values to a plane from below, i.e., values are raised to the plane. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state.

Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the plane value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.

Image.clampPlaneInplace(image, plane, region, fillMissingData)
Arguments:
Return type:

Image

Inplace version of the Image.clampPlane function that modifies the input image. See base function for full documentation.

Image.clampPolynomial(image, polynomial, region, fillMissingData)
Arguments:
Return type:

Image

Clamps image pixel values to a 2nd order polynomial from below, i.e., pixel values are raised to the polynomial. In case of overflow, the value is instead clamped to the maximal representable value. A partial region of operation may be selected, reducing the processing time. All pixels outside the region are left in an undefined state.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The polynomial is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: By default, a missing data pixel in the input image generates a missing data pixel in the output image. If the fillMissingData flag is set to true, all pixels with missing data will be set to the polynomial value and the missing data flag of the output image will be cleared. In that case, the full range of raw pixel values may be used.

Image.clampPolynomialInplace(image, polynomial, region, fillMissingData)
Arguments:
Return type:

Image

Inplace version of the Image.clampPolynomial function that modifies the input image. See base function for full documentation.

Image.clone(image)
Argument:
Return type:

Image

Returns a duplicated instance of the input image. New memory to copy all pixel data is allocated.

Image.concatenate(image1, image2, direction)
Arguments:
Return type:

Image

Concatenates two images.

Image world coordinate system handling: The image world coordinate system is used to update the output image origin. The new origin depends on how image2 is placed in relation to image1 (direction), the different possibilities are: - ABOVE (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1-image2Height*image2PixelSizeY, Ozimage1) - BELOW (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - RIGHT (Oxout, Oyout, Ozout) = (Oximage1, Oyimage1, Ozimage1) - LEFT (Oxout, Oyout, Ozout) = (Oximage1-image2Width*image2PixelSizeX, Oyimage1, Ozimage1) Both input images must have the same pixel size, inherited by the output image.

Missing data handling: The output image missing data flag is inherited from image1.

Image.convolve(image, kernel, region)
Arguments:
Return type:

Image

Calculates the cross correlation of the input image with the selected kernel. Please note that although the filter is named convolve a cross correlation is calculated and not a convolution. If a convolution is required it can be achieved by rotating the kernel. The result of the cross correlation is cropped so that the output image has the same size as the input image. If the complete cross correlation output is required please pad the input image according to the kernel size. The pad function also allows to specify what border type to use. Border handling is so that the values outside the image are treated as zero.

Image world coordinate system handling: The convolve filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to relate ensuing thresholding of the output image to the input world z-scale.

Missing data handling: This function does not accept missing data images, fill in the missing data pixels or toggle the missing data flag prior to calling this function.

Image.create(width, height, type)
Arguments:

  • width (int)

  • height (int)

  • type (enum)

Return type:

Image

Creates a new image of a certain size and pixel type.

Image.createFromMemory(buffer, width, height, type)
Arguments:

  • buffer (binary)

  • width (int)

  • height (int)

  • type (enum)

Return type:

Image

Creates a new image of a certain size and pixel type by copying the data of a binary buffer.

Image.crop(image, x, y, width, height)
Arguments:

  • image (Image)

  • x (int)

  • y (int)

  • width (int)

  • height (int)

Return type:

Image

Crops a subpart of an image, specified in pixel coordinates. A cropped image is a clone of the source data.

Image.cropRectify(image, shape)
Arguments:
Return type:

Image

Crops the region defined by a rotated rectangle or a closed polyline, and also rotates/transforms the cropped image patch to become axis-aligned using a linear interpolation operation. The size of the output image is determined automatically to obtain approximately the same pixel resolution as the input image has. If the crop region extends outside the input image borders, the corresponding pixels in the output image get the value 0.

For a Shape Rectangle type region input, the function crops and rotates the content within the rectangle to a new image. The rotation of the input rectangle is reversed so that the output is defined by a zero-degree-rotated rectangle with the same width and height as the input rectangle.

For a Shape Polyline type region input, it is a requirement that the polyline has exactly 4 points and that it encloses a convex region, e.g., it must not self-intersect. The function then crops the defined region and applies a homography transform to transform the content into an axis-aligned bounding box. The order of the four points in the polyline is relevant. The following mapping from points in the polyline to corners in the output image patch is made: - 1st point maps to upper left corner - 2nd point maps to upper right corner - 3rd point maps to lower right corner - 4th point maps to lower left corner.

The transform from the input shape (Rectangle or Polyline region) and the output image is also provided. With this transform it is possible to map features, e.g., points, from the input image to the cropped image, and vice versa with the inverse of the transform. The transform is of rigid type when possible and of homography type otherwise.

Image world coordinate system handling: New x,y pixel sizes are calculated, based on the input shape and input image. For example, a 90 degree rotated rectangle as a shape would just swap the pixel sizes in x and y in the output image. For non-rectangular shapes the average pixel sizes in the x,y-dimensions are used.

Missing-data handling: For images with the missing data flag set, missing data aware sampling will be used and the output image will also set its missing data flag. Values being sampled outside of the image will get the value 0.

Image.cropRegion(image, region, paddingPix)
Arguments:
Return type:

Image

Crops the region defined by the bounding box of an input pixelregion. Optionally, padding around the bounding box can also be specified in order to extend it. The pixelregion bounding box is defined by the limits of its non-empty pixels. If the pixelregion contains values outside of the input image the intersection of the pixelregion with the image region is used.

The output cropped pixelregion is a copy of the region corresponding to the padded pixelregion bounding box (crop region). The cropped image contains a copy of the values inside the crop region. The image size is equal to the size of the crop region, the pixel size is the same as the input image and the image origin value is equal to the top left corner of the crop region.

Image world coordinate system handling: The image world coordinate system is copied from the input image, only the origin changes to the value of the top left corner of the crop region.

Missing-data handling: The missing data information is kept from the input image.

Image.demosaic(inputImage, desiredMode)
Arguments:

  • inputImage (Image)

  • desiredMode (enum)

Return type:

Image

Bayer pattern demosaicing. Only UINT8 and UINT32 is supported. If an UINT32 image, each pixel (32bit) comes from 2x2 pixels with RGGB, where R is the least significant bits.

Image.difference(image1, image2, differenceMode)
Arguments:

  • image1 (Image)

  • image2 (Image)

  • differenceMode (enum)

Return type:

Image

Computes the pixel-wise difference between two images, using a configurable difference operator. The images must be of equal size and pixel type, and have the same pixel size and origin in the z-dimension.

Difference operators: ABS: Absolute difference, |image1 - image2|. SQUARE: Squared difference, (image1 - image2)^2.

Return image type: The return image type for all integer image types is unsigned. For SQUARE difference operator, a larger integer type is returned, e.g. UINT16 if the input is INT8.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Image.distanceTransform(image, region)
Arguments:
Return type:

Image

Applies the distance transform operation on the input image. Each pixel in the output image gives the approximate Euclidean distance to the closest background pixel (value = 0) in the input image. Typically the input image is a binarized image with 0:s representing the background and some other value (e.g. 1 or 255) representing the foreground. Currently only the uint8 pixel type is supported.

Image world coordinate system handling: The image world coordinate system is not considered in this function. The distances in the output image are in pixel units, i.e., not scaled with the world pixel sizes in x and y. The output image inherits the image world coordinate system of the input image in the x,y dimensions, but the z-origin is set to 0 and the z-pixelsize is set to 1 regardless of the input values.

Missing data handling: The function does not consider the missing data flag of the input image. The missing data flag of the output will be set to false, i.e., no missing data.

Image.divide(image1, image2)
Arguments:
Return type:

Image

Divides two images pixelwise. The images must be of equal size and pixel type. A division-by-zero leads to a 0 in the output image. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. In case of an underflow in the arithmetic, raw pixel values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.divideInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.divide function which modifies the first input image to contain the ratio of the input images. See base function for full documentation.

Image.drawPixelRegion(image, regions, decoration)
Arguments:
Return type:

Image

Render one or several PixelRegions into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB.

The View.PixelRegionDecoration object is used to set the color of the rendered regions.

Image world coordinate system handling: The input PixelRegion is interpreted in raw pixel coordinates, the image world coordinate system is not considered.

Missing data handling: This function does not use the missing data flag.

Image.drawPixelRegionInplace(image, shapes, decoration)
Arguments:
Return type:

Image

Inplace version of the Image.drawPixelRegion function which modifies the input image. See base function for full documentation.

Image.drawPoint(image, points, decoration)
Arguments:
Return type:

Image

Render the position of one or several points into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. to RGB.

The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the color of the points. - The PointType property is used to render points as circles or crosses. - The PointSize property is used to set the size of the rendered points.

Image world coordinate system handling: The points coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the points properly.

Missing data handling: This function does not use the missing data flag.

Image.drawPointCloud(image, pointcloud, decoration)
Arguments:

  • image (Image)

  • pointcloud (PointCloud)

  • decoration (View.PointCloudDecoration)

Return type:

Image

Render one or several pointclouds into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. The x- and y- coordinates of each point in the pointcloud are used to place each point into the image world coordinate system.

Points are rendered using the information in the PointCloudDecoration object. The following properties in the PointCloudDecoration object are supported: - The ZRange or IntensityRange parameters: If there is a ZRange set, the colors of the rendered points will be based on the z-values. Otherwise the intensity component of each point is used, either using the IntensityRange parameter or using the default range for intensity colors which is 0 to 1.

  • The PointSize parameter.

Image world coordinate system handling: The world coordinate system of the image if respected and each point in the pointcloud is drawn at the corresponding image position.

Missing data handling: This function does not use the missing data flag.

Image.drawPointCloudInplace(image, pointcloud, decoration)
Arguments:

  • image (Image)

  • pointcloud (PointCloud)

  • decoration (View.PointCloudDecoration)

Return type:

Image

Inplace version of the Image.drawPointCloud function which modifies the input image. See base function for full documentation.

Image.drawPointInplace(image, points, decoration)
Arguments:
Return type:

Image

Inplace version of the Image.drawPoint function which modifies the input image. See base function for full documentation.

Image.drawProfile(image, profiles, decoration)
Arguments:

  • image (Image)

  • profiles (Profile)

  • decoration (View.GraphDecoration)

Return type:

Image

Render one or several profiles into an image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. For profiles with 1D coordinates the coordinate vector is mapped to the x-axis of the image and the value vector to the y-axis. Each sample in the profile is then drawn in the image world coordinate system. For profiles with 2D coordinates the value vector is discarded and the profile is drawn on its coordinates in the image world coordinate system.

Note: This function differs from the View.addProfile function in that it does not provide the full graph plotting functionality as a dedicated graph viewer does, e.g., coordinate axes, background grids etc. are not rendered with the drawProfile function. Color and line width properties are controlled using the View.GraphDecoration object. The two properties used for this are the GraphColor and DrawSize properties in the GraphDecoration object. No other properties in the GraphDecoration are currently supported.

Image world coordinate system handling: The world coordinate system of the image if respected and each profile is drawn at the corresponding image position.

Missing data handling: This function does not use the missing data flag.

Image.drawProfileInplace(image, profiles, decoration)
Arguments:

  • image (Image)

  • profiles (Profile)

  • decoration (View.GraphDecoration)

Return type:

Image

Inplace version of the Image.drawProfile function which modifies the input image. See base function for full documentation.

Image.drawShape(image, shapes, decoration)
Arguments:
Return type:

Image

Render the position of one or several shapes into an RGB image. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB.

The View.ShapeDecoration object is used to set graphical properties. The following parameters in the ShapeDecoration object are supported: - The LineColor property is used to set the border color of the rendered shape. - The FillColor property is used to set the fill color of the rendered shape. - The LineWidth property is used to set width of the border.

Image world coordinate system handling: The shape coordinates are interpreted as world coordinates. That is, the coordinate system of the image is used to place the shapes properly.

Missing data handling: This function does not use the missing data flag.

Image.drawShapeInplace(image, shapes, decoration)
Arguments:
Return type:

Image

Inplace version of the Image.drawShape function which modifies the input image. See base function for full documentation.

Image.drawText(image, text, decoration)
Arguments:
Return type:

Image

Renders text into an image by modifying the pixel values. The input image must be of either RGB or UINT8 type. Use Image.toRGB or Image.applyColormap to convert other image types to RGB. Not all features of the TextDecoration input are supported. Features that are supported are the following: * Position - Fully supported. * Color - Does not support opacity. * Size - Approximately matching to viewer settings. * Font family - SANSSERIF and SERIF are supported, MONOSPACE is unsupported. * Font weight - Fully supported, but does not exactly match viewer behavior. * Horizontal alignment - Full support apart from JUSTIFY, but does not exactly match viewer behavior. * Vertical alignment - Fully supported, but does not exactly match viewer behavior

Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font position will adjust to the image coordinate system, but the font size will only scale with the y-resolution.

Missing data handling: This function does not use the missing data flag.

Image.drawTextInplace(image, text, decoration)
Arguments:
Return type:

Image

Inplace version of the Image.drawText function that modifies the input image. See base function for full documentation.

Image.equalizeHistogram(image, region)
Arguments:
Return type:

Image

Applies histogram equalization to an image.

Image.exp(image)
Argument:
Return type:

Image

Applies the natural exponential to the value at each pixel. The output will be an image of type FLOAT32 (or FLOAT64 in case the input is already FLOAT64).

Image world coordinate system handling: The z-scale of the image is considered. The image metadata from the input image is copied to the output image except for the z-scale and z-origin, values are instead stored in world coordinates directly.

Missing data handling: Missing data is not supported and the missing data flag must be toggled off.

Image.extractColumnProfile(image, column, startRow, stopRow, sampleCoordinates1D)
Arguments:

  • image (Image)

  • column (int)

  • startRow (int)

  • stopRow (int)

  • sampleCoordinates1D (boolean)

Return type:

Profile

Extracts profile(s) from an image column(s). The number of samples in the profile is always the same as the number of pixels between the start and end row (end position is included).

Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image column to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image column and the delta vector the spacing between pixels in the y-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the y-coordinates of the sampled pixels.

Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.

Image.extractEdgeProfile(image, polyLine, maxDistance, contrastThreshold, selection, polarity, side)
Arguments:

  • image (Image)

  • polyLine (Shape)

  • maxDistance (float)

  • contrastThreshold (float)

  • selection (enum)

  • polarity (enum)

  • side (enum)

Return type:

Profile

Samples an edge relative to a polyline. The sampling is done by placing a number of probe lines along the polyline. The probe lines are placed orthogonal to each segment of the polyline. If an edge point is not found along a given probe line, the corresponding sample in the output profiles is marked as invalid. The distance between each probe line along the polyline is min(pixelSizeX, pixelSizeY).

Coordinate system handling: The sample coordinates in the edgeDistance profile are the 1D distances along the polyline, in world coordinates. The sample coordinates in the edgeStrength profile are the positions of the found edges in the image, in world coordinates.

Missing data handling: Edges between data and missing data are valid in images with missing data.

Image.extractProfile(image, shape, sampleCount, interpolation)
Arguments:

  • image (Image)

  • shape (Shape)

  • sampleCount (int)

  • interpolation (enum)

Return type:

Profile

Samples image values evenly along a contour defined by a 2D Shape object and generates a Profile object. Supported shape types are line segment, arc, circle and polyline.

Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The coordinate representation in the generated Profile object will be of implicit type if the contour shape allows it. For example, coordinates along a line segment contour can be represented using the implicit start + delta vector representation. For more complex contours such as a circle, an explicit coordinate representation is used in the Profile object where all the sample points are stored as individual entries. If the contour shape is closed, e.g., a circle, the closed flag in the Profile is also set.

Missing data handling: Valid data flags are enabled in the output profile if and only if the image has missing data activated. Points sampled on missing data are marked as invalid. Points sampled outside the image are marked as invalid. In the latter case and if the image does not have missing data activated, the valid flags of the generated profile are set accordingly but are not enabled.

Image.extractRowProfile(image, row, startColumn, stopColumn, sampleCoordinates1D)
Arguments:

  • image (Image)

  • row (int)

  • startColumn (int)

  • stopColumn (int)

  • sampleCoordinates1D (boolean)

Return type:

Profile

Extracts profile(s) from an image row(s). The number of samples in the profile is always the same as the number of pixels between the start and end column (end position is included).

Coordinate system handling: The image world coordinate system is considered when generating the Profile object, i.e., the image origin and pixelsizes in the (x,y) dimensions will be reflected in the coordinates of the Profile object. The z-origin and z-pixelsize are considered when generating the measurement values in the Profile object. The image row to extract from is provided as a zero-based integer pixel coordinate. The coordinate representation in the generated Profile object will be of implicit 2D or 1D type. Default is 2D, where the start point is the (x,y) world coordinates of the first extracted pixel in the image row and the delta vector the spacing between pixels in the x-dimension. Optionally, 1D coordinates can be returned, in which case the sample coordinates are set to the x-coordinates of the sampled pixels.

Missing data handling: Valid data flags are enabled in the output profile if and only if the image contains missing data. Points sampled on missing data pixels are marked as invalid.

Image.fillRegion(inputImage, region, value)
Arguments:
Return type:

Image

Set all pixels within the given region(s) in the target image to a specific value in world coordinates. The pixels outside the input region keep their original values. A new image with updated values is returned, and the input image is left unchanged.

Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. If the value parameter is outside the image value range it will be clamped to the closest valid value. The output image inherits the image world coordinate system of the input image.

Missing data handling: The missing data flag is kept in the output image, but the pixels in the fill region will be updated with non missing data.

Image.fillRegionInplace(image, region, value)
Arguments:
Return type:

Image

Inplace version of the Image.fillRegion function that modifies the input image. See base function for full documentation.

Image.findColumnMax(image, region, method, intensityThreshold, certaintyThreshold)
Arguments:

  • image (Image)

  • region (Shape)

  • method (enum)

  • intensityThreshold (float)

  • certaintyThreshold (float)

Return type:

Profile

Extract the position of the brightest values in each column of an image. The methods employed does not only find one bright pixel but uses the neighborhood of each pixel to find a robust subpixel positions of the peak. In reality the line is typically created by a laser projector and this function is used for laser triangulation, although it may be used in other ways. Detection can be improved by providing an axis aligned rectangle shape for the region to search in. This both helps with performance and noise suppression as points outside of the region will be omitted from consideration. The intensity threshold determines how bright a column has to be to give a value in the output profile. Setting the intensity threshold too high removes detections completely. The certainty threshold determines what certainty is required for the valid flag of the profile to be true. Setting the certainty threshold high will still give detections, but will mark the concerned entries as invalid.

Image world coordinate system handling: The x-axis origin and pixel size are not used. Each column will generate one coordinate in the output profile. The y-axis origin and pixel size are used to decide the final values of the profile. The z-axis origin and pixel size are not used. The max is found in raw coordinates.

Missing data handling: Missing data is not supported.

Image.findGlobalThreshold(image, binCount, minValue, maxValue, region)
Arguments:
Return type:

float

Get the global threshold of the image values within the specified region. This threshold can be used to separate pixels into two classes, foreground and background. The Otsu’s method was used to compute the threshold, the key idea is to use a histogram to minimize the intra-class intensity variance. If the image supports missing data, pixels marked as missing are not included in the histogram. If a pixel-world mapping is specified, the histogram is computed using world coordinates. If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. See also Image.getHistogram.

Image.findLineSegments(image, scale, region, mergeLines)
Arguments:
Return type:

Shape

Finds line segments in an image. Returns a list of 2D line segments represented as a Shape type. An empty list is returned when no line segments were found during an otherwise successful call. This function is currently limited to uint8 pixel type images.

Image world coordinate system handling: The output Shape line segments are expressed using the image world coordinate system in the xy-dimensions. The z-dimension is not used in this function.

Missing data handling: This function does not support images with missing data. Fill in missing data before hand, using e.g., missingDataSetAll.

Image.findLocalExtrema(image, extremaType, neighborhoodSize, contrastThreshold, contrastDifferenceMode, absoluteThreshold, region)
Arguments:

  • image (Image)

  • extremaType (enum)

  • neighborhoodSize (int)

  • contrastThreshold (float)

  • contrastDifferenceMode (enum)

  • absoluteThreshold (float)

  • region (Image.PixelRegion)

Return type:

Image.PixelRegion

Finds local extreme points (minima or maxima) in an image. A point is a local maxima if it is larger than all points within a neighborhood of the specified size. An optional contrast threshold level can be defined that sets a required value difference between the local maxima and the smallest value in the neighborhood. For local plateaus, where several pixels have the same value, the top left pixel is reported. An absolute threshold can be specified, if so, point values must exceed the threshold value to be reported. Local minima are detected similarly. Early stopping is used, the neighborhood is only searched until it is clear that the pixel at hand is not an extremal point, starting with the four closest neighbor pixels. The function thus runs faster on smooth images. The absoluteThreshold can also be used to speed up the processing, only considering pixels larger (smaller) than the threshold. The entire neighborhood must fit within the image around extreme points e.g. if neighborhoodSize = 5, no extreme points will be detected closer than three pixels from the image border.

Image world coordinate system handling: The thresholds are specified in world values, taking z-origin and pixel size into account. The output pixel region is defined on the pixel grid of the image.

Missing data handling: This function does not handle missing data. Remove missing data before calling this function.

Image.gauss(image, kernelSizePix, region, fillMissingData, gaussianFilterType)
Arguments:

  • image (Image)

  • kernelSizePix (int)

  • region (Image.PixelRegion)

  • fillMissingData (boolean)

  • gaussianFilterType (enum)

Return type:

Image

Applies a Gaussian filter to smooth an image.

Image world coordinate system handling: The Gaussian filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image.

Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Image.getFlatRegion(image, threshold, neighborhoodSize, fast, pixelRegion)
Arguments:
Return type:

Image.PixelRegion

Find approximately flat regions in an image, typically a heightmap or distance image. The algorithm fits a plane to a local neighborhood around each pixel. If all pixel values / z-values in the neighborhood deviate less than a user-specified threshold from the fitted plane, the central pixel is considered to be in a flat region. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable.

Image world coordinate system handling: Every position in the output region will have a maximum distance to the fitted plane in world units evaluated on the all pixels under the kernel that is lower than the threshold supplied.

Missing data handling: Missing data is accepted, but partly ignored. No pixels that are missing in the input will be part of the output region. For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly breaking the flatness constraint.

Image.getFlatness(image, neighborhoodSize, fast, pixelRegion)
Arguments:
Return type:

Image

Calculates a flatness measure for each pixel in an image. A pixel with a value close to zero means approximate coplanarity with its neighbors. The algorithm fits a plane to a local neighborhood around each pixel and gives out the maximum deviation from the plane over all pixels in the neighborhood. There is a fast and slow method for the plane fitting, where the slower method uses all pixels in the neighborhood to estimate the plane and the fast method only uses the border values in the neighborhood. Smoothing the input image first using a blur, gauss or median filter can sometimes be advisable.

Image world coordinate system handling: Every pixel in the flatness image stores the maximum distance to the fitted plane in world units evaluated on the all pixels under the neighborhood.

Missing data handling: Missing data is accepted, but partly ignored. All pixels that are missing data in the input image will get a negative planarity measure (corresponding to 1 z-pixelsize ). For pixels neighboring missing data the missing data positions are allowed to influence the flatness evaluation, possibly inflating the flatness measure.

Image.getHeight(image)
Argument:
Return type:

int

Returns the height of an image.

Image.getHistogram(image, binCount, minValue, maxValue)
Arguments:

  • image (Image)

  • binCount (int)

  • minValue (float)

  • maxValue (float)

Return type:

float

Get a histogram of the image values. If the image supports missing data, pixels marked as missing are not included in the histogram. The histogram is computed using world coordinates (z-axis offset and scaling have influence). If the bounds are skipped, the entire image value range is used for 8-channel images, and the range between the current minimum and maximum value is used for other image types. Pixels with values outside the interval are not counted. See also Image.PixelRegion.getHistogram.

Image.getLocalMean(image, points, neighborhoodRadius, referenceSurface)
Arguments:
Return type:

float

Get the mean pixel value within a circular neighborhood of a point. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having mean value NaN.

Image world coordinate system handling: Image world coordinate system values are used.

Missing data handling: Missing data pixels are not included.

Image.getLocalMedian(image, points, neighborhoodRadius, referenceSurface)
Arguments:
Return type:

float

Get the median value of the pixels within a circular neighborhood of a point, a special case of Image.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference surface in world coordinates may be provided, in which case the deviations from the reference surface are considered. The default surface is the plane z=0. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having median value NaN.

Image world coordinate system handling Image world coordinate system values are used.

Missing data handling: Missing data pixels are not included.

Image.getLocalStatistics(image, points, neighborhoodRadius, referenceSurface)
Arguments:
Return type:

float

Get pixel value statistics within a circular neighborhood of a point. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of points can be provided, in which case four vectors of statistics are returned, one entry for each input point. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having all values NaN.

Image world coordinate system handling: Image world coordinate system values are used.

Missing data handling: Missing data pixels are not included.

Image.getLocalStd(image, points, neighborhoodRadius, referenceSurface)
Arguments:
Return type:

float

Get the standard deviation of the pixel values within a circular neighborhood of a point. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. When using multiple points, point neighborhoods which are empty or have no valid data are reported as having standard deviation value NaN.

Image world coordinate system handling: Image world coordinate system values are used.

Missing data handling: Missing data pixels are not included.

Image.getMax(image, region)
Arguments:
Return type:

float

Returns the maximum pixel value in an image. The position of the first maximal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided.

Image world coordinate system handling: The output value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale.

Missing data handling: Missing data pixels are ignored.

Image.getMean(image, region, referenceSurface)
Arguments:
Return type:

float

Get the mean pixel value. If a region is provided, the mean is calculated within that region. By default, a reference plane z=0 is used. Another reference plane may be provided, giving the mean difference from that plane. Several regions in a list may be used, in which case one mean value is calculated for each region. When using multiple regions, regions which are empty or have no valid data are reported as having mean value nan.

Image world coordinate system handling: The output mean value is specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale.

Missing data handling: Missing data pixels are not included.

Image.getMedian(image, region, referenceSurface)
Arguments:
Return type:

float

Get the median value of the pixels within the region, a special case of Image.getPercentiles. The median is derived from a histogram and it is approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0. A vector of points can be provided, the median is then calculated in the neighborhood of each points in the vector. If a median value can’t be calculated a NaN value is returned.

Image.getMin(image, region)
Arguments:
Return type:

float

Returns the minimum pixel value in an image. The position of the first minimal value pixel and its uniqueness is also returned. Optionally, a pixel region may be provided.

Image world coordinate system handling: The output value is specified in image world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale.

Missing data handling: Missing data pixels are ignored.

Image.getMinMax(image, region)
Arguments:
Return type:

float

Returns the minimum and maximum pixel value in an image. Optionally, a pixel region may be provided.

Image world coordinate system handling: The output min and max values are specified in world coordinates, i.e., the origin and pixel size in the z-dimension are used to convert the raw pixel value to world scale.

Missing data handling: Missing data pixels are ignored.

Image.getMissingDataFlag(image)
Argument:
Return type:

int

Gets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Image.getMissingDataImage(image, missingValue, dataValue)
Arguments:

  • image (Image)

  • missingValue (int)

  • dataValue (int)

Return type:

Image

Creates a binary image indicating the missing data pixels in the source image.

Image world coordinate system handling: The output binary image gets the same x,y-origin and x,y-pixelsize as the input image, but the z-origin is set to 0 and the z-pixelsize to 1.

Missing data handling: The output image has no missing data flag set as it is a binary image.

Image.getMissingDataRegion(image)
Argument:
Return type:

Image.PixelRegion

Creates a PixelRegion object of all missing data pixels in the source image.

Image.getOrigin(image)
Argument:
Return type:

Point

Retrieves the origin of the image world coordinate in the image. The origin corresponds to the world coordinate of the top-left image pixel.

Image.getOriginZ(image)
Argument:
Return type:

float

Retrieves the z-origin of the image world coordinate in the image.

Image.getPercentiles(image, percentileLevels, region, referenceSurface)
Arguments:
Return type:

float

Get a set of rank measurement according to the specified percentile levels. Level 0.5 gives the median, level 0.9 give a value larger than 90% of all image pixels, etc. All values are derived from a histogram and are approximate. Optionally, a reference plane in world coordinates may be provided, in which case the deviations from the reference plane are considered. The default surface is the plane z=0.

Image.getPixel(image, x, y, pixelValueType)
Arguments:

  • image (Image)

  • x (int)

  • y (int)

  • pixelValueType (enum)

Return type:

float

Returns the pixel value of an image at position (x,y) in pixel coordinates. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.

Image.getPixelSize(image)
Argument:
Return type:

float

Retrieves the pixel size of the image world coordinate system.

Image.getPixelSizeZ(image)
Argument:
Return type:

float

Retrieves the pixel size in the z-dimension of the image world coordinate system.

Image.getSize(image)
Argument:
Return type:

int

Returns the width and height of an image.

Image.getStatistics(image, region, referenceSurface)
Arguments:
Return type:

float

Get pixel value statistics. If a region is provided, the statistics is calculated within that region. Image world coordinate system values are used and pixels with missing data are excluded. By default, the reference surface z=0 is used. Another reference surface (plane) may be provided, basing the statistics on deviations from that surface. If the statistics can not be calculated, nil is returned. A vector of regions can be provided, in which case four vectors of statistics are returned, one entry for each input region. Any invalid input region in the vector will have the corresponding output entries set to zero.

Image.getSum(image)
Argument:
Return type:

float

Returns the sum of the pixel values in an image.

Image world coordinate system handling: The sum is in world coordinates, i.e., the origin and pixel size in the z-dimension are considered should the image represent a height map, distance or range image.

Missing data handling: This operation does not support missing data images, fill in missing data before calling this function.

Image.getType(image)
Argument:
Return type:

enum

Returns the pixel type of the image.

Image.getValidDataRegion(image)
Argument:
Return type:

Image.PixelRegion

Creates a PixelRegion object of all non-missing data pixels in the source image.

Image.getWidth(image)
Argument:
Return type:

int

Returns the width of an image.

Image.getWorldZ(image, points)
Arguments:
Return type:

float

Returns the z-values at given 2D (x,y)-points, interpreting the image as a range image. Linear interpolation is used for positions between the pixel grid positions. For points outside the image the z-origin value is return corresponding to raw pixel value 0.

Coordinate system handling: The image world coordinate system is used in this operation, i.e., the input 2D points are interpreted using the pixelsizes and origin in the (x,y)-dimensions and the output z value is also in world coordinates.

Missing data handling: Missing data is respected so that missing data pixels are ignored in the interpolation calculation.

Image.growRegion(image, seedRegion, minThreshold, maxThreshold)
Arguments:
Return type:

Image.PixelRegion

Starting from the seed regions, the regions are expanded to fill the pixel areas whose world pixel values in the image lies between the lower and upper threshold in world coordinates. Pixels with missing data are not grown into. Pixels included in the seed region will always be included in the output region, independent of the corresponding pixel value and missing status.

Image world coordinate system handling: The thresholds are interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 or a z-pixelsize different than 1.

Missing data handling: Pixels with missing data are not included in the grown region, unless covered by the seed region.

Image.houghTransformCircle(edgeImage, radius, resolutionX, resolutionY)
Arguments:

  • edgeImage (Image)

  • radius (float)

  • resolutionX (int)

  • resolutionY (int)

Return type:

Image

Finds circle candidates with a given radius in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over circle centers in world coordinates. The world coordinates of the output accumulator directly matches circle centers, i.e. the world coordinates of a maxima in the accumulator image corresponds directly to the input image circle center in world coordinates. Use Image.houghTransformExtremaToCircles to create circles from accumulator image maxima (as a pixel region), or extract maxima as points and use Shape.createCircle(points, radius) directly.

Image world coordinate system handling: Input image world coordinates are used. The radius is in world coordinates. The accumulator world coordinates directly relate maxima to circle centers. Pixel values in the input image are interpreted in raw pixel values.

Missing data handling: Missing data are interpreted as not edges.

Image.houghTransformExtremaToCircles(accumulatorImage, extremalRegion, radius)
Arguments:
Return type:

Shape

Converts pixels extracted from an accumulator image obtained from houghTransformCircle to geometrical circles. The accumulator image is required to get the world coordinate system and accumulator values. Results are sorted in descending order by accumulator value.

Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Circles are returned in world coordinates.

Missing data handling: Not applicable, there is no missing data in the input accumulator image.

Image.houghTransformExtremaToLines(accumulatorImage, extremalRegion, edgeImage, removeDuplicates)
Arguments:
Return type:

Shape

Converts pixels extracted from an accumulator image obtained from houghTransformLine to geometrical lines. Both the accumulator and edge images are required to get the world coordinate system. Since horizontal lines end up just where the accumulator image wraps around, the accumulator is usually extended with a few extra rows. These may result in duplicate line detections (the direction differ by pi, with opposite sign of the distance to the image center). By default, such duplicate lines are removed but this feature can be turned off. The accumulator value corresponding to each line candidate is returned. Results are sorted in descending order by accumulator value.

Image world coordinate system handling: Pixel region of extremas should be related to the accumulator image. Lines are returned in world coordinates of the original input image.

Missing data handling: Not applicable, there is no missing data in the input accumulator image.

Image.houghTransformLine(edgeImage, distanceBins, directionBins, overlapBins, directionCenter, directionRange)
Arguments:

  • edgeImage (Image)

  • distanceBins (int)

  • directionBins (int)

  • overlapBins (int)

  • directionCenter (float)

  • directionRange (float)

Return type:

Image

Finds line candidates in an edge image where any non-zero pixel is considered an edge. The output is an accumulator image binned over line candidate direction and signed distance from the center of the input image. E.g. a line candidate with direction pi/2 and distance -5 is a vertical line located five world coordinate units to the left of the center point of the input image. Line candidates are on the form x*sin(theta) + y*cos(theta) = d, where x and y are input image positions relative to the center of the input image, d is the signed distance from the center of the input image and theta is the line direction. All are expressed in world coordinates. d is binned over distanceBins bins which also is the width of the output image. Theta is binned over directionBins bins. The range of theta is from zero to pi, d is from minus to plus half the diagonal of the input image. Since the direction parameter is circular in nature, a maxima at the upper and lower accumulator image border (theta is zero or pi) with opposite signs of d correspond to the same line. Since maxima extraction routines tend to skip maxima close to image borders, a few extra rows are added to the bottom of the accumulator image, corresponding to the first rows of accumulators. The number of extra rows is set by the overlapBins parameters, recommended to be set to the maxima extraction filter size. The accumulator image height is thus directionBins + overlapBins. The search space can be limited by setting the directionCenter and directionRange parameters. The direction search range is centered around the direction center. If set, the rows of the accumulator image are distributed over the specified direction range and no overlap bins are added. The first row of the accumulator image corresponds to directionCenter - directionRange/2. The canny function can be used to generate an edge image suitable as input. The threshold or findLocalExtrema functions can be used to find extrema in the accumulator image. Use houghTransformExtremaToLines to transform extrema from the accumulator image into Shape lines.

Image world coordinate system handling: Input image world coordinates are used. All output values are with respect to the center of the input image. The output image world coordinates are set to directly get d and theta values. Raw pixel values of the input image are used.

Missing data handling: Missing data are interpreted as not edges.

Image.inpaint(image, region, radius, method)
Arguments:
Return type:

Image

Replaces the image content in a specified region with the content around the region. This is done in an iterative manner and increasing the radius increases the speed of the algorithm, at the cost of quality of the result.

Image world coordinate system handling: The world coordinate system of the input image is not used. The output will have the same coordinate system as the input image.

Missing data handling: Operation is performed in raw pixel values. If there are missing data along the borders of the region it will be used for inpainting.

Image.invert(image, maxValue)
Arguments:

  • image (Image)

  • maxValue (float)

Return type:

Image

Inverts the pixel values in the image, so that dark becomes bright and vice versa. The operation imOutput = getMax(imInput) - imInput. To do an inversion in the sense 1/x use the pow-function.

Image world coordinate system handling: The output image keeps the coordinate system of the input image. The z-component of the output image origin is set to zero, this makes the inversion correct both for world pixel values and raw pixel values.

Missing data handling: A missing data pixel in the input image results in a missing data pixel in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.invertInplace(image, maxValue)
Arguments:

  • image (Image)

  • maxValue (float)

Return type:

Image

Inplace version of the Image.invert function that modifies the input image. See base function for full documentation.

Image.isEqual(image1, image2, tolerance, compareMetaData)
Arguments:

  • image1 (Image)

  • image2 (Image)

  • tolerance (float)

  • compareMetaData (boolean)

Return type:

boolean

Checks if two images are equal, both in terms of size, type and pixel content. This function disregards the image world coordinate information and looks only at raw pixel values.

Image.isWithinBounds(image, x, y)
Arguments:

  • image (Image)

  • x (int)

  • y (int)

Return type:

boolean

Checks whether a pixel coordinate is within the bounds of the image.

Image.laplace(image, kernelSizePix, region)
Arguments:
Return type:

Image

Applies a Laplace filter to the input image, i.e., the sum of the local second-order gradients in the x- and y-directions.

Image world coordinate system handling: The Laplace filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale.

Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Image.load(filepath)
Argument:

  • filepath (string)

Return type:

Image

Loads an image from the specified file path. The format is defined by the file extension: .bmp: Bitmap .png: PNG .jpg/jpeg: JPEG (not supported by all devices) .pgm: PGM (not supported by all devices) .json: JSON AppSpace format (redirects to Object.load) .msgpack: MessagePack AppSpace format (redirects to Object.load)

Image.log(image)
Argument:
Return type:

Image

Applies the natural logarithm to the value at each pixel. The output will be an image of type FLOAT32 (or FLOAT64 in case the input is already FLOAT64). Negative and zero values have no representation and will be presented as NaN and negative infinity respectively.

Image world coordinate system handling: The z-scale of the image is considered. The image metadata from the input image is copied to the output image except for the z-scale and z-origin, values are instead stored in world coordinates directly.

Missing data handling: Missing data is not supported and the missing data flag must be toggled off. Input values of zero will be returned as negative infinity.

Image.max(image1, image2)
Arguments:
Return type:

Image

Creates an image with the maximum pixel values of the source images. The images must be of equal size and pixel type.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Image.maxInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.max function which modifies the first input image to contain the pixelwise maximum of the input images. See base function for full documentation.

Image.median(image, kernelSizePix, region, fillMissingData, preserveDetails)
Arguments:

  • image (Image)

  • kernelSizePix (int)

  • region (Image.PixelRegion)

  • fillMissingData (boolean)

  • preserveDetails (boolean)

Return type:

Image

Applies median filter to the image to smooth and remove noise.

Image world coordinate system handling: The median filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image.

Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Image.min(image1, image2)
Arguments:
Return type:

Image

Creates an image with the minimum pixel values of the source images. The images must be of equal size and pixel type.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. The input images are allowed to have different image world coordinate systems, but only the z-pixelsizes and z-origins are utilized, pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image.

Image.minInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.min function which modifies the first input image to contain the pixelwise minimum of the input images. See base function for full documentation.

Image.mirror(image, mirrorHorizontally)
Arguments:

  • image (Image)

  • mirrorHorizontally (boolean)

Return type:

Image

Mirrors an image in the horizontal or vertical axis.

Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is mirrored.

Missing data handling: All missing data values will be retained after mirroring.

Image.missingDataReduce(inputImage, method, nSize, region)
Arguments:
Return type:

Image

Reduces missing data pixels in an image by using valid values in the neighborhood. Valid pixel values are unaffected. This will fill in scattered missing data values but larger patches of missing data will remain. The type of operation performed to fill a missing pixel is selected using the method parameter. Optionally, reduction of missing data can be limited to a region in the image. Valid pixel values within a neighborhood but outside the region will still be used to fill missing data. To fill a missing pixel, at least one quarter of the neighbor pixels need to have valid values.

The available methods are: MAX - Sets missing pixels to the maximum valid value in the neighborhood. MIN - Sets missing pixels to the minimum valid value in the neighborhood. MEAN - Sets missing pixels to the mean of all valid values in the neighborhood. MEDIAN - Sets missing pixels to the median of all valid values in the neighborhood. EDGE - Fills missing values by edge-preserving interpolation among pixels in the 3x3 pixel neighborhood. A missing data pixel will be filled in only if there are valid values on both sides of a pixel.

For all methods except EDGE, the neighborhood is nSize-by-nSize pixels. nSize must be odd and at least three. For method EDGE, nSize determines how many times the algorithm will be repeated. For EDGE, nSize must be a positive integer.

Image.missingDataSetAll(image, valueWorld, region)
Arguments:
Return type:

Image

Sets all missing data pixels in the entire image or within a specified region to a given value. All missing pixels are set and the missing data flag of the image is cleared. If a region is provided, only pixels within the region are considered. The missing data flag of the image is still cleared, leaving any pixels with missing data outside the region in an undetermined state.

Image world coordinate system handling: The specified value parameter is interpreted in image world coordinates, e.g., in millimeters if the source image is a range image with a z-origin different than 0 and a z-pixelsize different than 1. The output image inherits the image world coordinate system of the input image.

Missing data handling: The missing data flag is removed from the output image, also if the operation is only performed within a region of interest.

Image.missingDataSetAllInplace(image, valueWorld, region)
Arguments:
Return type:

Image

Inplace version of the Image.missingDataSetAll function that modifies the input image. See base function for full documentation.

Image.missingDataSetSurface(image, surface, region)
Arguments:
Return type:

Image

Sets all missing data pixels to the surface value, values are clamped to the representable range of the image. All valid values are left unchanged. If a region not covering the full image is used, any missing data outside the region will be left in an undetermined state. Currently, either a plane surface represented as a Shape3D or a 2nd order polynomial extracted by the Image.SurfaceFitter is supported, other surface types may be supported in the future.

For a 2nd order polynomial surface, the following representation is expected z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The surface is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: This function replaces all missing data pixels with the surface value. The missing data flag for the output image is removed, also when this operation is performed only within a specified region of interest.

Image.missingDataSetSurfaceInplace(image, surface, region)
Arguments:
Return type:

Image

Inplace version of the Image.missingDataSetSurface function which sets all missing data pixels to a surface value. See base function for full documentation.

Image.mixColorize(background, overlay, min, max, imageWeight)
Arguments:

  • background (Image)

  • overlay (Image)

  • min (float)

  • max (float)

  • imageWeight (float)

Return type:

Image

Mix two images using a predefined colormap from blue to red. One image represent the general background and the other which color to mix in. The background image can be either a single channel UINT8 image or a three channel RGB image. Generally this function can be used to visualize error values over an input image. Values below the limit of the colormap will remain the same as in the background input image. Values above the limit of the colormap will saturate towards the upper end of the colormap. To use a custom colormap see the related function Image.mixColormap.

The colormap created by this function corresponds to the following stops and colors. colormap:addStop(0.0, 0, 0, 127) colormap:addStop(0.125, 0, 0, 255) colormap:addStop(0.375, 0, 255, 255) colormap:addStop(0.625, 255, 255, 0) colormap:addStop(0.875, 255, 0, 0) colormap:addStop(1.0, 127, 0, 0)

Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension of the overlay image is used in world coordinates to find the color of the colormap.

Missing data handling: Missing data values are not affected in the background image. The overlay image must be float32 and missing data may need preprocessing before conversion.

Image.mixColormap(background, overlay, colormap, imageWeight)
Arguments:

  • background (Image)

  • overlay (Image)

  • colormap (View.ColorMap)

  • imageWeight (float)

Return type:

Image

Mix two images using a colormap. One image represent the general background and the other which color of the supplied colormap to mix in. The background image can be either a single channel UINT8 image or a three channel RGB image. Generally this function can be used to visualize error values over an input image. Values below the limit of the colormap will remain the same as in the background input image. Values above the limit of the colormap will saturate towards the upper end of the colormap. For a simpler interface with a predefined colormap see the related Image.mixColorize function.

Image world coordinate system handling: The image content is converted and the coordinate system preserved except for the value dimensions. The value dimension of the overlay image is used in world coordinates to find the color of the colormap.

Missing data handling: Missing data values are not affected in the background image. The overlay image must be float32 and missing data may need preprocessing before conversion.

Image.morphology(imageIn, diameterPix, transform, region)
Arguments:
Return type:

Image

A morphological transformation applied to grayscale images. The possible transformation types are: ERODE, DILATE, OPEN, CLOSE, GRADIENT, TOPHAT and BLACKHAT. A circular structuring element/kernel is used for all types. The diameter of the kernel can be specified by diameterPix. For erosion the basic idea is just like soil erosion, it erodes away the boundaries of an object making it thinner. The dilation is the opposite transformation. The elements of the kernel contain: 0-background or 1-foreground. It is centered at each image pixel and defines the neighborhood pixels to be used. For grayscale erosion the new pixel value corresponds to the minimum value of the image pixels under the structuring element foreground. Similarly, for grayscale dilation the maximum of the neighborhood is used. The remaining transformations are: opening - erosion followed by dilation; closing - dilation followed by erosion; morphological gradient - difference between dilation and erosion; top hat - difference between input image and opening; black hat - difference between closing and input image.

Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The diameter of the structuring element is in pixel units, i.e., not scaled with the world pixel sizes in x and y.

Missing data handling: This function does not handle missing data images. Fill in the missing data pixels and/or remove the missing data flag from the image before calling.

Image.mosaic(image, tileWidth, tileHeight, xOverlap, yOverlap)
Arguments:

  • image (Image)

  • tileWidth (int)

  • tileHeight (int)

  • xOverlap (int)

  • yOverlap (int)

Return type:

Image

Crops an image into a vector of smaller tiles. The mosaic tiles can be specified to overlap. A valid tile must be completely within the source image, i.e., tiles that would partly extend outside the image at the right and bottom borders of the source image are not included in the output vector. The vector of tiles is sorted row wise so that all the tiles covering the uppermost part of the image come first.

Image.multiply(image1, image2)
Arguments:
Return type:

Image

Multiplies two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate value. The second image is treated as a unit-less modifier and it must therefore have a standard image world coordinate system with pixel sizes all equal to 1 and origins equal to 0. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. Note that it is possible to obtain 0 as result of the multiplication and that such pixels then will be considered as missing data in subsequent processing steps.

Image.multiplyAddConstant(image, alpha, beta)
Arguments:

  • image (Image)

  • alpha (float)

  • beta (float)

Return type:

Image

Multiplies an image pixelwise by a constant alpha and then adds a second constant beta: alpha*Image + beta. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.multiplyAddConstantInplace(image, alpha, beta)
Arguments:

  • image (Image)

  • alpha (float)

  • beta (float)

Return type:

Image

Inplace version of Image.multiplyAddConstant function which modifies the input image. See base function for full documentation.

Image.multiplyConstant(image, constant)
Arguments:

  • image (Image)

  • constant (float)

Return type:

Image

Multiplies all pixels in the image with a constant value. If there is underflow or overflow in the arithmetic operation, the output pixel values are clamped to the min or max limit of the pixel data type, with an exception for images containing missing data, see below.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example a height map, distance or range image, multiplication of the world z-value is done, considering the z-origin and z-pixelsize. The image metadata from the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw pixel values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.multiplyConstantInplace(image, constant)
Arguments:

  • image (Image)

  • constant (float)

Return type:

Image

Inplace version of Image.multiplyConstant function which modifies the input image. See base function for full documentation.

Image.multiplyInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.multiply function which modifies the first input image to contain the product of the input images. See base function for full documentation.

Image.multiplyProfile(image, profile, dimension)
Arguments:

  • image (Image)

  • profile (Profile)

  • dimension (enum)

Return type:

Image

Returns the image with the profile multiplied with all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row.

Image world coordinate system handling: The input image coordinate system is transferred to the output image. The operation is performed in the world coordinate system. The z-origin of the input image must be zero.

Missing data handling: Missing data in the image will remain in the output image. Missing data in the profile will leave the corresponding image values unchanged.

Image.multiplyProfileInplace(image, profile, dimension)
Arguments:

  • image (Image)

  • profile (Profile)

  • dimension (enum)

Return type:

Image

Inplace version of the Image.multiplyProfile function that modifies the input image. See base function for full documentation.

Image.normalize(image, lowerBound, upperBound, region)
Arguments:
Return type:

Image

Scales the raw pixel values linearly so that all pixels fit into a given range (lowerBound, upperBound). Keeps the world values constant. Target bounds outside the representable range of the image type are accepted. In that case, pixel values are clamped to the representable range.

Image world coordinate system handling: The world coordinate system of the output image along the value axis z is chosen such that the world pixel values remains unchanged unless clamping occurs. For integer type images, rounding to integer raw pixel values will change the world values slightly. Other meta data are copied from the input image.

Missing data handling: Pixels with missing data remain marked as missing in the output. For images with the missing data flag set, raw pixel values are clamped to 1 instead of 0 to avoid introducing more pixels marked as missing.

Image.pad(imageIn, topPaddingPix, bottomPaddingPix, leftPaddingPix, rightPaddingPix, borderType, intensity)
Arguments:

  • imageIn (Image)

  • topPaddingPix (int)

  • bottomPaddingPix (int)

  • leftPaddingPix (int)

  • rightPaddingPix (int)

  • borderType (enum)

  • intensity (float)

Return type:

Image

Image padding, adds a border to the image.

Image world coordinate system handling: The image world coordinate system is used to update the output image origin, it is calculated as follows: (Oxout, Oyout, Ozout) = (Oxin - pixelSizeX * leftPaddingPix, Oyin - pixelSizeY * topPaddingPix, Ozin), the world pixel sizes remain the same. The boundary paddings are in pixel units, i.e., not scaled with the world pixel sizes in x and y.

Missing data handling: This function does not use the missing data flag. If the padding contains zeros it will be treated as missing data if the flag is on.

Image.pow(image, exponent)
Arguments:

  • image (Image)

  • exponent (float)

Return type:

Image

Applies an exponent to the value at each pixel. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel data type respectively.

Image world coordinate system handling: The z-scale of the image is considered, but the operation is not implemented for images with z-origin different from 0.0. The image metadata from the input image is copied to the output image.

Missing data handling: In case of an underflow in the arithmetic, values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.powInplace(image, exponent)
Arguments:

  • image (Image)

  • exponent (float)

Return type:

Image

Inplace version of the Image.pow function which modifies the input image. See base function for full documentation.

Image.renderPlane(image, plane)
Arguments:
Return type:

Image

Renders a plane to an image, clamping values to the representable range of the image. The output image is of the same type as the input image.

Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image.

Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.

Image.renderPlaneInplace(image, plane)
Arguments:
Return type:

Image

Inplace version of the Image.renderPlane function which modifies the input image by adding the value of a given plane. See base function for full documentation.

Image.renderPolynomial(image, polynomial, offsetZ)
Arguments:

  • image (Image)

  • polynomial (float)

  • offsetZ (float)

Return type:

Image

Renders a 2nd order polynomial into an image, clamping values to the representable range of the image. The output image is of the same type as the input image.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The surface is rendered in the world space defined by the reference image, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the reference image is copied to the output image.

Missing data handling: The missing data flag of the reference image is copied to the output image. If the flag is set, raw pixel values are clamped to 1 instead of 0 to avoid generating pixels with missing data.

Image.renderPolynomialInplace(image, polynomial, offsetZ)
Arguments:

  • image (Image)

  • polynomial (float)

  • offsetZ (float)

Return type:

Image

Inplace version of the Image.renderPolynomial function which modifies the input image by adding the value of a given polynomial. See base function for full documentation.

Image.renderText(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
Arguments:

  • image (Image)

  • text (string)

  • positionWorld (Point)

  • fontSizePix (int)

  • fontThicknessPix (int)

  • value (float)

Return type:

Image

Renders text into an image by modifying the pixel values.

Image world coordinate system handling: The image world coordinate system is copied from the input image, only the image content is changed. The font parameters and text position are in pixel units, i.e., not scaled with the world pixel sizes in x and y.

Missing data handling: This function does not use the missing data flag.

Image.renderTextInplace(image, text, positionWorld, fontSizePix, fontThicknessPix, value)
Arguments:

  • image (Image)

  • text (string)

  • positionWorld (Point)

  • fontSizePix (int)

  • fontThicknessPix (int)

  • value (float)

Return type:

Image

Inplace version of the Image.renderText function that modifies the input image. See base function for full documentation.

Image.replace(sourceImage, replacingImage, region)
Arguments:
Return type:

Image

Replaces the image content in a specified region with the content of another image. The images must have the same pixel type.

Image world coordinate system handling: The world coordinate systems of the input images are not used. The output will have the same coordinate system as the first input image.

Missing data handling: Raw pixel values are copied as they are. If there are missing data within the region in the replacing image, the source image pixels will be replaced by missing data.

Image.replaceInplace(sourceImage, replacingImage, region)
Arguments:
Return type:

Image

Inplace version of the Image.replace function which modifies the first input image by replacing pixel values with pixel values from another image. See base function for full documentation.

Image.resize(image, width, height, method)
Arguments:

  • image (Image)

  • width (int)

  • height (int)

  • method (enum)

Return type:

Image

Resizes an image to a given size in pixels. Different interpolation methods can be used.

Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.resizeScale(image, fx, fy, method)
Arguments:

  • image (Image)

  • fx (float)

  • fy (float)

  • method (enum)

Return type:

Image

Resizes an image by a scale factor. Different interpolation methods can be used.

Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, are copied directly from the input image.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.rotate(image, rotationRad, origin, method, grid)
Arguments:

  • image (Image)

  • rotationRad (float)

  • origin (Point)

  • method (enum)

  • grid (enum)

Return type:

Image

Rotates an image around the center of the image. Optionally a different origin of rotation can be specified.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.rotate90(image, rotationSteps)
Arguments:

  • image (Image)

  • rotationSteps (int)

Return type:

Image

Rotates an image +90, -90 or 180 degrees. A positive rotation is in the clockwise direction. The pixels are rearranged and no interpolation takes place, making the operation faster than a general rotation.

Image world coordinate system handling: For plus and minus 90 degree rotations, the x- and y-pixel sizes are swapped so that the width and height are also swapped. The image origin is copied from the input image.

Missing data handling: Missing data is rotated in the same way as the input image.

Image.save(image, filepath, compression)
Arguments:

  • image (Image)

  • filepath (string)

  • compression (string)

Return type:

boolean

Saves an image to the specified file path. Overwrites the file if it already exists. Supported pixel types are: UINT8, UINT16, INT8, INT16, INT32, FLOAT32 and FLOAT64. The format is defined by the file extension: .bmp: Bitmap, no data compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are not saved. .pgm: Portable gray map, no data compression. (Optional compression parameter can be used to set the bit depth in the pgm header. Only smaller values are allowed. E.g. 8 bit image -> Valid compression parameter: [0 … 255]). Image origin, pixel size and missing data flag are not saved. .png: PNG (not supported by all devices), lossless data compression. (Compression level can be controlled by compression parameter. Allowed values are “0” to “9”. Default is “6”.) Image origin, pixel size and missing data flag are not saved. For pixel types INT8, INT16, INT32, FLOAT32 and FLOAT64 the values are clamped to 0-255. .jpg: JPEG (not supported by all devices), lossy data compression. Not supported on all devices. (Quality can be controlled by compression parameter. Allowed values are “0” to “100”. Default is “95”) Image origin, pixel size and missing data flag are not saved. .json: JSON AppSpace format (redirects to Object.save), no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved. .msgpack: MessagePack AppSpace format (redirects to Object.save), no compression. (Optional compression parameter not supported). Image origin, pixel size and missing data flag are saved.

Image.setAll(image, value)
Arguments:

  • image (Image)

  • value (float)

Sets all raw pixel values in an image to the specified value. Currently only supports scalar pixel types, i.e., not RGB. Pixels with missing data are also set. Setting all pixels to zero on an image with the global missing data flag set, all pixels will be marked as missing.

Image.setColumn(image, values, column, startRow)
Arguments:

  • image (Image)

  • values (float)

  • column (int)

  • startRow (int)

Return type:

boolean

Fills in a column of an image with the value(s) provided. Values are given in world coordinates (e.g. millimeters). Note that this function operates inplace. If a scalar value is provided, all rows from startRow to the image height will be filled with the value. If the provided value(s) is a vector of length N, N rows will be filled with these values starting at row startRow.

Coordinate system handling: The image world coordinate system is only considered along the value range. Values are clamped to fit the pixel value range of the target image.

Missing data handling: A missing data image may be used as the target image. Values to be set are clamped to the valid range of the target image, that is, the value to be set is clamped such that it is always marked as a valid value. Temporarily disable the missing data flag to allow setting values that will be regarded as missing (raw pixel value zero).

Image.setColumnProfile(image, profile, column, startRow)
Arguments:

  • image (Image)

  • profile (Profile)

  • column (int)

  • startRow (int)

Return type:

boolean

Fills in a column of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image column starting at row startRow. The number of values set are equal to the length of the profile.

Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels.

Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Image.setMissingDataFlag(image, missingDataFlag)
Arguments:

  • image (Image)

  • missingDataFlag (int)

Sets the missing data setting in the image. 0 means no missing data handling, 1 means that the value 0 is treated as missing data.

Image.setOrigin(image, origin)
Arguments:
Return type:

boolean

Sets the origin of the image world coordinate system in the image. The origin corresponds to the image world coordinate of the top-left pixel. If a 2D point is provided, the origin is unchanged in the z-direction.

Image.setOriginZ(image, originZ)
Arguments:

  • image (Image)

  • originZ (float)

Sets the z-origin of the image world coordinate system in the image.

Image.setPixel(image, x, y, value, pixelValueType)
Arguments:

  • image (Image)

  • x (int)

  • y (int)

  • value (float)

  • pixelValueType (enum)

Set the pixel value or a vector of pixel values in an image at position(s) (x,y) to the given pixel value. For monochrome image types this is a single float value, for RGB24 a vector of three float values in the order red, green, blue.

Image.setPixelSize(image, sizeX, sizeY, sizeZ)
Arguments:

  • image (Image)

  • sizeX (float)

  • sizeY (float)

  • sizeZ (float)

Sets the pixel size in world coordinates. If the size in the Z direction is omitted, the Z size is unchanged.

Image.setPixelSizeZ(image, sizeZ)
Arguments:

  • image (Image)

  • sizeZ (float)

Sets the pixel size in the z-dimension in world coordinates, e.g., the number of millimeters each pixel value integer increment corresponds to.

Image.setRow(image, values, row, startColumn)
Arguments:

  • image (Image)

  • values (float)

  • row (int)

  • startColumn (int)

Return type:

boolean

Fills in a row of an image with the value(s) provided. Values are given in world coordinates (e.g. millimeters). Note that this function operates inplace. If a scalar value is provided, all columns from startColumn to the image width will be filled with the value. If the provided value(s) is a vector of length N, N columns will be filled with these values starting at column startColumn.

Coordinate system handling: The image world coordinate system is only considered along the value range. Values are clamped to fit the pixel value range of the target image.

Missing data handling: A missing data image may be used as the target image. Values to be set are clamped to the valid range of the target image, that is, the value to be set is clamped such that it is always marked as a valid value. Temporarily disable the missing data flag to allow setting values that will be regarded as missing (raw pixel value zero).

Image.setRowProfile(image, profile, row, startColumn)
Arguments:

  • image (Image)

  • profile (Profile)

  • row (int)

  • startColumn (int)

Return type:

boolean

Fills in a row of an image with the values taken from a profile. Note that this function operates inplace. The values in the profile is filled into the image row starting at column startColumn. The number of values set are equal to the length of the profile.

Coordinate system handling: The image world coordinate system is only considered along the value range, i.e., the profile z origin and pixelsize is used to scale the profile before placing it in the image. The x and y coordinate of the profile and image are ignored and the values are simply placed in the designated image pixels.

Missing data handling: If the source profile contains invalid points the target image must be a missing data image. Missing data is propagated from profile to image.

Image.sobel(image, region)
Arguments:
Return type:

Image

Applies the standard 3x3 Sobel filter operator to find gradients and edges in the x- and y-directions.

Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale.

Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Image.sobelMagnitude(image, region, metric)
Arguments:
Return type:

Image

Calculates the magnitude of the standard 3x3 Sobel operator gradient responses dx and dy to find edges in the input image.

Image world coordinate system handling: The Sobel filter kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image in the xy-dimensions. In the z-dimension, the z-origin is set to 0 but the z-pixelsize is inherited from the input image to be able to related ensuing thresholding of the output image to the input world z-scale.

Missing data handling: This function does not accept missing data images, fill in the missing data pixels prior to calling this function.

Image.splitRGB(imageRGB)
Argument:
Return type:

Image

Splits an RGB image into the individual R, G, B color components. The input RGB image must be of 8-bit RGB type.

Image.stdDev(image, kernelSizePix, region, fillMissingData)
Arguments:
Return type:

Image

Calculates a local standard deviation around each pixel. Also returns the local average (the same as from Image.blur).

Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image.

Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Image.subtract(image1, image2)
Arguments:
Return type:

Image

Subtracts two images pixelwise. The images must be of equal size and pixel type. If there is underflow or overflow in the arithmetic operation, the output pixel value is clamped to the min and max limit of the pixel type, with an exception for images containing missing data, see below.

Image world coordinate system handling: The first input image is treated as the main image whose metadata is copied to the output image. The operation is interpreted as operating on the world z-coordinate values. Pixel sizes and origins in the x- and y-dimensions are not considered and have no effect on the operation.

For unsigned integer types it can be useful to first apply Image.adjustOriginZ() to image1 to avoid clamping the results to 0. For images A, B subtracting B from A would cause clamping when values in B are larger than those in A by such a large amount that the difference exceeds the Z-origin of A. By adjusting the origin of A to a smaller value this can be remedied.

Missing data handling: A missing data pixel in any of the two input images generates a missing data pixel in the output image. For missing data images, as the value 0 is reserved, clamping to 1 instead of 0 is done for underflows and when the pixel type is unsigned integer.

Image.subtractInplace(image1, image2)
Arguments:
Return type:

Image

Inplace version of the Image.subtract function which modifies the first input image to contain the difference of the input images. See base function for full documentation.

Image.subtractPlane(image, plane, region, autoAdjustOriginZ)
Arguments:
Return type:

Image

Subtracts a plane from an image. For every pixel, the corresponding plane z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting autoAdjustOriginZ true for unsigned integer data, the origin of the result image will be adjusted to avoid clamping at zero. Using automatic origin adjustment on a partial region of the image will not compensate the pixel values outside the region for the new origin, such pixels will appear with an offset in global coordinates.

Image world coordinate system handling: The plane is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.subtractPlaneInplace(image, plane, region, autoAdjustOriginZ)
Arguments:
Return type:

Image

Inplace version of the Image.subtractPlane function which modifies the input image by subtracting the value of a given plane. See base function for full documentation.

Image.subtractPolynomial(image, polynomial, region, offsetZ)
Arguments:
Return type:

Image

Subtracts a 2nd order polynomial from an image. For every pixel, the corresponding polynomial z-value is subtracted. If there is underflow or overflow for integer type images, the output value is clamped to the min and max limit of the pixel data type. A partial region of operation may be selected, reducing the processing time. By setting offsetZ to a value other than zero, the origin of the result image can be adjusted to avoid clamping.

Note that the functions Image.thresholdPolynomial and Image.binarizePolynomial exist for object segmentation.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The polynomial is interpreted in world space and subtracted from the image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. The metadata of the input image is copied to the output image.

Missing data handling: Missing data pixels in the input image are also missing data pixels in the output image. In case of an underflow in the arithmetic, raw values are clamped to 1 instead of to 0 in order to avoid creating new missing data in the output image.

Image.subtractPolynomialInplace(image, polynomial, region, offsetZ)
Arguments:
Return type:

Image

Inplace version of the Image.subtractPolynomial function which modifies the input image by subtracting the value of a given polynomial. See base function for full documentation.

Image.subtractProfile(image, profile, dimension)
Arguments:

  • image (Image)

  • profile (Profile)

  • dimension (enum)

Return type:

Image

Returns the image with the profile subtracted from all rows or all columns depending on the dimension argument. The dimension argument is optional and if not provided processing is done row by row.

Image world coordinate system handling: The input image coordinate system is transferred to the output image. The input profile is subtracted in world coordinates.

Missing data handling: Missing data in the input image remains missing in the output image. For missing data in the profile, the image data will be unchanged. If missing data, note that the minimum pixel value is always 1 for valid pixels.

Image.subtractProfileInplace(image, profile, dimension)
Arguments:

  • image (Image)

  • profile (Profile)

  • dimension (enum)

Return type:

Image

Inplace version of the Image.subtractProfile function that modifies the input image. See base function for full documentation.

Image.thin(image, region)
Arguments:
Return type:

Image

Applies a morphological thinning, also known as skeletonization, using the Guo-Hall algorithm. It is typically performed on an already binarized input image. Zeros in the input image (raw pixel value) are interpreted as background pixels. Note: The algorithm can be slow for large images with many non-zeros (large binary objects). Consider operating on regions of interest if possible. Pixels outside the region of interest may be set to any value.

The output is a binary image with the skeleton indicated by pixels set to 1.

Image world coordinate system handling: The image world coordinate system is not considered in this function. The output image inherits the x,y origin and x,y pixelsize. The z-origin should be set to 0 and z-pixelsize to 1 in the input image.

Missing data handling: The missing data flag should be cleared in the input image and is cleared in the output image.

Image.threshold(image, lowerThreshold, upperThreshold, regionOfInterest)
Arguments:
Return type:

Image.PixelRegion

Threshold the image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). Return the result as a PixelRegion object.

Image world coordinate system handling: The input thresholds are interpreted in the image world coordinate system considering the z-origin and z-pixelsize, e.g., in millimeter scale if the image would represent a range image with z-origin different from 0 of a z-pixelsize different from 1. A conversion is done within the function to raw pixel value thresholds.

Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Image.thresholdColor(image, lowerThresholds, upperThresholds, regionOfInterest, colorSpace, invertRanges)
Arguments:

  • image (Image)

  • lowerThresholds (float)

  • upperThresholds (float)

  • regionOfInterest (Image.PixelRegion)

  • colorSpace (enum)

  • invertRanges (boolean)

Return type:

Image.PixelRegion

Threshold a color image by keeping all pixels with a value between lowerThreshold and upperThreshold (inclusive). If the color system selected is RGB, threshold1 controls the R channel, threshold2 the G channel and threshold3 the R channel. All channels have range: [0, 255]. If the color system selected is HSV, threshold1 controls the H channel with range [0, 360] degrees, threshold2 the S channel and threshold3 the V channel with ranges [0,100]%. Return the result as a PixelRegion object.

Missing data handling: Missing data is not supported.

Image.thresholdCompare(image, referenceImage, marginWorld, findBright, regionOfInterest)
Arguments:
Return type:

Image.PixelRegion

Threshold an image by pixelwise comparison with a reference image. All pixels with a value greater than or equal to the corresponding reference image value are included in the output PixelRegion object. An optional margin (positive or negative) may be provided, adjusting the reference image values prior to the comparison. A larger positive margin results in fewer included pixels. The optional flag findBright may be set to false, returning the region where the image is lower/darker than the reference image. A region of interest can be provided, limiting the processing to that region. The images must be of the same pixel type and be of equal size. This function gives a PixelRegion objects as output, to get a binary image as output use binarizeCompare instead.

Image world coordinate system handling: To allow for an efficient comparison, the z-pixelsizes of the input images must be equal but the z-offsets may differ. The margin parameter is interpreted in image world coordinates, e.g., as a millimeter margin if the input is a range image.

Missing data handling: Missing data pixels are excluded from the output PixelRegion object.

Image.thresholdPlane(image, lowerThreshold, upperThreshold, plane, region)
Arguments:
Return type:

Image.PixelRegion

Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided plane (inclusive). Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference plane is also supported, using relative thresholds with the same sign.

Image world coordinate system handling: The plane is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system.

Missing data handling: No pixel marked as missing is included in the output region.

Image.thresholdPolynomial(image, lowerThreshold, upperThreshold, polynomial, region)
Arguments:
Return type:

Image.PixelRegion

Thresholds the image by keeping all pixels with a world value between lowerThreshold and upperThreshold relative to the provided 2nd order polynomial. Returns the result as a PixelRegion object. Thresholding values strictly below or above the reference polynomial is also supported, using relative thresholds with the same sign.

The expected input 2nd order polynomial is of the following form z = Ac + Ax*x + Ay*y + Axx*x*x + Axy*x*y + Ayy*y*y where Ac, Ax, Ay, Axx, Axy, Ayy are the coefficients.

Image world coordinate system handling: The polynomial is interpreted in world space which is compared with image world z-value of each pixel, taking care of the pixel sizes and origins in x,y,z of the image. Thresholds are interpreted in the world coordinate system, e.g., in millimeter unit.

Missing data handling: No pixel marked as missing is included in the output region.

Image.toGray(imageRGB, redWeight, greenWeight, blueWeight)
Arguments:

  • imageRGB (Image)

  • redWeight (float)

  • greenWeight (float)

  • blueWeight (float)

Return type:

Image

Converts an RGB image into a gray value image.

Image.toHSV(imageRGB)
Argument:
Return type:

Image

Converts an RGB image into individual HSV color space components. The Hue-component is usually represented as an angle in the interval [0,360], but to fit in a uint8 image the value is divided by 2 to be in the interval [0,180].

Image.toLab(imageRGB)
Argument:
Return type:

Image

Converts an RGB image into individual Lab color space components.

Image.toMatrix(inputImage)
Argument:
Return type:

Matrix

Creates a matrix from a monochrome image. Each entry in the matrix corresponds to the pixel value scaled by the image world Z coordinates. Missing data is set to NaN in the matrix.

Image.toMesh(image, calcNormals, intensity, color)
Arguments:
Return type:

Mesh

Creates a mesh from an image. The image values are interpreted in world units and are used to create one vertex from each pixel.

The intensity input is optional and can be used to set the intensity of the mesh. The mesh intensities are represented as values between 0 and 1. To use a UINT8 image as source set the pixel size in z to 1/255. The color input is also optional and must be an image of RGB type. It can be used alone or together with the intensity input. The final mesh color is a mix of the intensity and color data such that the final color is intensity*color.

Image world coordinate system handling: The image world coordinate system is used to create the mesh, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-vertices of the mesh.

Missing data handling: For images with missing data the missing values will be represented as mesh coordinates with the z value set to nan.

Image.toPixelCoordinate(image, worldCoordinate)
Arguments:
Return type:

Point

Converts an image world coordinate to a pixel coordinate.

Image.toPixelZ(refImage, worldZCoordinate)
Arguments:

  • refImage (Image)

  • worldZCoordinate (float)

Return type:

float

Converts a z world coordinate value to a raw pixel value using the image world coordinate system supplied by the input reference image. The mapping pixelValue = (worldZCoordinate - originZ)/pixelSizeZ is made.

Image.toPointCloud(image, removeMissing, intensity, region)
Arguments:
Return type:

PointCloud

Creates a pointcloud from image(s). Typically one heightmap input image is used in which the pixel pitch is constant in each dimension. The alternative use cases are to supply separate images for either x and z or for x, y and z coordinates. In total there are three ways this can be used:

  1. Image.toPointCloud(range, true/false, intensity, region)

  2. Image.toPointCloud({X, Z}, true/false, intensity, region)

  3. Image.toPointCloud({X, Y, Z}, true/false, intensity, region)

In case 1 the pixel sizes and origin of the range image is used to create the X and Y coordinates. In case 2 the pixel sizes and origin of of Z is used to create the Y coordinates in the output. In case 3 all positions are uniquely determined by the input images X, Y and Z. Pixel sizes and origin in the input images are unused.

The intensity and region inputs are optional and can be used to set the intensity of the output pointcloud and to remove points respectively.

Image world coordinate system handling: in general the image world coordinate system is used to create the pointcloud, i.e. the (x, y, z)-pixel sizes and origins are used to create the (x, y, z)-components of the pointcloud. For details see the longer text above.

Missing data handling: For images with missing data it is possible to select to keep or remove the missing points. If missing points are kept they are marked as such in the pointcloud and will be black in intensity. If they are removed the grid structure of the image is lost and the point cloud will be considered an unordered point cloud.

Image.toRGB(imageR, imageG, imageB, colorSpace)
Arguments:
Return type:

Image

Creates an RGB image from three grayscale images. The input images must be of uint8 type.

Image.toSquarePixels(image, upsample, method)
Arguments:

  • image (Image)

  • upsample (boolean)

  • method (enum)

Return type:

Image

Resizes an image to have square pixels, i.e., to have equal pixelsizes in the x and y dimensions. Having square pixels is sometimes required for further processing.

Image world coordinate system handling: The coordinate system of the output image will be slightly adjusted in relation to the input to take into account pixel size changes. Eg. both the origin and pixel size of the image will typically change. World positions in the image should be retained such that for example overlay graphics can remain on the same position after a rescaling. Values in z, both origin and pixel size, will be copied directly from the input image.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.toString(image)
Argument:
Return type:

string

Gets a user-friendly string description of the image, containing all properties but no actual pixel values.

Image.toType(image, type)
Arguments:

  • image (Image)

  • type (enum)

Return type:

Image

Converts an image to a new image of specified pixel type. The raw pixel values are casted and there may be underflow/overflow effects when casting to a type of lower capacity. For example, the value 256 in a uint16 image will overflow to 0 if converted to a uint8 type. To avoid such effects, clamp the input pixel values to the min and max values of the target pixel type. When converting from a monochrome image to RGB, all channels are set to the same value. Use toRGB to convert three monochrome images into a color image or splitRGB to split a color image into three monochrome images.

Image.toTypeFit(image, targetType, minValue, maxValue, clamp)
Arguments:

  • image (Image)

  • targetType (enum)

  • minValue (float)

  • maxValue (float)

  • clamp (boolean)

Return type:

Image

Converts a gray value image into another gray value image of a different type. The input image values are rescaled to fit the target type. For integer images without missing data the min and max values provided are mapped to the limits of the data type. World values outside of these limits in the input image are clamped to the min and max of the data type. For integer images with missing data the clamping option allows to either discard values that are out of range or to clamp them to the limits in the same way as for non-missing data images. Set clamping to false to discard values. For float images the min and max value provided will be mapped to 0 and 1. The clamping option selects if values outside the provided interval should clamp or be allowed to extend beyond the range 0 and 1.

Image world coordinate system handling: The boundaries are provided in world coordinates of the input image. The output image is updated with an adjusted world coordinate system that as closely as possible maintain the absolute world values of the input in the result.

Missing data handling: For missing data images missing data is preserved. Note that for a missing data type input only unsigned integer output types are allowed. If clamping is set to false values outside the selected range are set to missing.

Image.toVector(inputImage)
Argument:
Return type:

float

Creates a vector from a monochrome image. If the vectors of each channel of a color image are needed please first split the channels using Image.splitRGB. Each entry in the vector corresponds to the raw pixel value. Missing data is set to 0. Please note, this function should be used with care for large images, because it can exhaust the memory of the device.

Image.toWorldCoordinate(image, pixelCoordinate)
Arguments:
Return type:

Point

Converts a pixel coordinate to an image world coordinate.

Image.toWorldZ(image, pixelValue)
Arguments:

  • image (Image)

  • pixelValue (float)

Return type:

float

Converts a pixel raw value to a z world coordinate value using the image world coordinate system supplied by the input reference image. The mapping worldZCoordinate = pixelValue*pixelSizeZ + originZ is made.

Image.transform(image, transform, method, grid)
Arguments:
Return type:

Image

Applies a linear geometric transform to an image. The result image uses the same pixel grid as the input image, if the SAME output grid is selected.

Image world coordinate system handling: If the image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the input image and the transformed image is by default (output grid SAME) repainted onto this coordinate system. Using output grid FULL, the output image size and origin is set to fit the entire output.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.transformInto(sourceImage, transform, destinationImage, method)
Arguments:
Return type:

Image

Applies a 2D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. The pixel grid and coordinate system of the destination image is used for transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes (except Z if an height map) of the output image - The world origin of the output image

All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image.

Image world coordinate system handling: If the image or destination image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is kept in the destination image and the transformed image is painted onto this coordinate system.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image. The missing data flags of the input and destination images must match.

Image.transformInto3D(sourceImage, transform, destinationImage, method, splatX, splatY, clearTarget)
Arguments:

  • sourceImage (Image)

  • transform (Transform)

  • destinationImage (Image)

  • method (enum)

  • splatX (int)

  • splatY (int)

  • clearTarget (boolean)

Return type:

Image

Applies a 3D linear geometric transform to an image and writes the result into the pixel grid defined by the destination image. Compared to the transformInto function, this function adds the possibility for 3D tilts. The function is typically used for heightmap image data.

The pixel grid and coordinate system of the destination image are used for the transform operation. Compared to the Image.transform function, this function gives a higher degree of control over the following parameters: - The size of the output image - The pixel sizes of the output image - The world origin of the output image

All the above properties are set by the input destination image. For example, a unit transform where the destination image has a world coordinate system different from the input image will resample the image.

Image world coordinate system handling: If the image or reference image has a non-default image world coordinate system, for example after calibration or in a height map, distance or range image, the operation is interpreted in image world coordinate units, e.g., millimeters. The image metadata is copied from the reference image and the transformed image is repainted onto this coordinate system.

Missing data handling: If using LINEAR as the method input, for an image with missing data, a missing data aware operation is performed. In situations were only one value is missing in the source image the target image is interpolated using the other valid samples. In cases with more than one missing value, missing data is returned in the output image. For method NEAREST missing data will remain if it is the nearest neighbor of the transformed pixels in the source image.

Image.variance(image, kernelSizePix, region, fillMissingData)
Arguments:
Return type:

Image

Calculates a the variance around each pixel. Also returns the local average (the same as from Image.blur).

Image world coordinate system handling: The kernel is specified in pixel coordinates, i.e., the xy-image world coordinates of the image are not considered in the interpretation of the kernel size. The output image inherits the image world coordinate system of the input image.

Missing data handling: For an image with the missing data flag set, the filtering will ignore the missing data pixels in the filtering operation so that they do not influence the result. Note that it is computationally more expensive to filter a missing data image though. While filtering, there is an option to fill in missing data pixels locally if possible. The amount filled in depends on the kernel size. If this option is not used, an missing data input pixel will generate a missing data output pixel. The output image inherits the missing data flag of the input image.

Image.warpSector(image, sector, interpolation)
Arguments:

  • image (Image)

  • sector (Shape)

  • interpolation (enum)

Return type:

Image

Warps the inner area of a sector shape to a rectilinear Cartesian grid.